Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 5 - Menu Manager Reference / Menu Manager Functions

Defining Your Own Contextual Menu Plug-In

NEW WITH CONTEXTUAL MENUS

A contextual menu plug-in is a subclass of AbstractCMPlugin : SOMObject. It consists of four methods:

• Initialize, which is called when the Menu Manager creates a list of available plug-ins
• ExamineContext, which is called when the user activates a contextual menu
• HandleSelection, which handles a contextual menu selection chosen by the user
• PostMenuCleanup, which performs any necessary cleanup or deallocation after the contextual menu is dismissed.

Note

A contextual menu plug-in is implemented as a SOMObject object inside a shared library. (SOMObjects for the Mac OS platform is the Mac OS implementation of the System Object Model.) Typically your development environment can compile directly to a SOMObject object, so you do not need to create your own SOM interfaces.

Each subclass of the AbstractCMPlugin must have an extended 'cfrg' resource, through which it identifies itself as a SOMObject object which derives from the AbstractCMPlugin class. See Mac OS Runtime Architectures for information about the extended 'cfrg' resource.

In addition you must register the plug-in class as a SOMObject object so that the Menu Manager can instantiate it by name. Typically you can do this in a fragment's initialization function.

Listing 5-1 shows a sample initialization function that registers the plug-in.

Listing 5-1 Registering a contextual menu plug-in

pascal OSErr MyPluginInitialize(CFragInitBlockPtr init)
{
   /* If your compiler creates a default initialization function,*/
   /* you should call it here */

   /* Now register our class with SOM */
      somNewClass(MyPlugIn);

   return noErr;
} 

The class declaration for a contextual menu definition plug-in is as follows:

class AbstractCMPlugin: SOMObject
{
   OSStatus Initialize(FSSpec *inFileSpec);
   OSStatus ExamineContext(AEDesc* inContextDescriptor, 
               SInt32 inTimeOutInTicks
               AEDescList* ioCommandPairs,
               Boolean* outNeedMoreTime);
   OSStatus HandleSelection(AEDesc* inContextDescriptor, SInt32 
               inCommandID);
   OSStatus PostMenuCleanup(void);
}

When writing your own contextual menu plug-in, you must follow this declaration and include the specified methods. The following sections describe these methods in detail.